home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / asm / amislib.exe / AMISLIB.DOC < prev    next >
Text File  |  1992-09-12  |  15KB  |  395 lines
  1. Alternate Multiplex Interrupt Specification Library
  2. Public Domain 1992 Ralf Brown
  3. Version 0.90
  4. LastEdit: 9/12/92
  5.  
  6. Files in this library:
  7.     AMISLIB.DOC    this file
  8.     TSRS.DOC    usage instructions for sample TSRs and utilities
  9.     AMIS.MAC    include file defining various macros
  10.     AMIS.ASM    the actual library code
  11.     AMISHOTK.ASM    the library's hotkey collision detection code
  12.     AMIS.H        C include file defining various things
  13.     AMITSRS.C    sample program to list resident programs using AMIS
  14.     FINDTSRS.C    function to find all TSRs matching a given name
  15.     POPUP.C        sample program to request popup of an AMIS TSR
  16.     REMOVE.C    sample program to remove a specific AMIS TSR
  17.     UNINSTAL.ASM    TSR remover for REMOVE.C
  18.     FASTMOUS.ASM    sample TSR
  19.     NOLPT.ASM    sample TSR -- turn parallel port into bit bucket
  20.     SWITCHAR.ASM    sample TSR -- provide switchar() for MSDOS 5.0
  21.     VGABLANK.ASM    sample TSR -- VGA screen blanker
  22.     NOTE.ASM    sample TSR -- popup note-taker
  23.     MAKEFILE    make all programs from the library sources
  24.  
  25. ------------------------------------------------------------------------
  26.  
  27. Advantages of AMISLIB:
  28.  
  29.     totally free
  30.     adds only 1K to the executable -- TSRs can be as small as 1.4K
  31.       on disk and use little as 128 bytes in memory (hotkey
  32.       checking adds another 300 bytes of transient code)
  33.     up to 256 AMIS-compliant TSRs can be resident simultaneously
  34.       with no interrupt conflicts
  35.     resultant TSR can load itself into high memory (either MSDOS 5
  36.       upper memory blocks or XMS upper memory blocks); the user has
  37.       control over where TSR is allowed to load: high only, low only,
  38.       or high first then low; high memory may use either the first or
  39.       the best UMB; low memory may use either the low end or the high
  40.       end of conventional memory.
  41.     TSRs using AMISLIB or other AMIS-compliant code can detect
  42.       hotkey conflicts and either abort before installation or
  43.       attempt to use alternate hotkeys
  44.     TSRs using AMISLIB or other AMIS-compliant code can be unloaded
  45.       in any order, and can be unloaded by programs other than the
  46.       TSR's original executable
  47.  
  48. Note: This is still a preliminary version of the library, so there might
  49.       be problems.  Please let me know if you find any....
  50.  
  51. ------------------------------------------------------------------------
  52.  
  53. To make use of this library, you basically need to do four things:
  54.  
  55.     1. To each source file that will make calls, add
  56.         INCLUDE AMIS.MAC
  57.     2. In the source file containing the program's entry point, add
  58.         @Startup M,NN,SSS
  59.        just after the above INCLUDE and
  60.         @Startup2 <Y>
  61.        at the program's entry point (see below for details).
  62.     3. Change the END line of the main source file to
  63.         END INIT
  64.     4. Link in AMIS.OBJ (assembled from AMIS.ASM) with the rest of
  65.        your object modules.     If you are using hotkeys, also link in
  66.        AMISHOTK.OBJ.
  67.  
  68. Limitations:
  69.     The ALTMPX and INSTALL_TSR macros must be invoked from the same
  70.       source file in order for the installer to properly fix up the
  71.       resident AMIS handler.  (If not, you will have to perform the
  72.       fixup yourself in an 'init' handler for INSTALL_TSR)
  73.     AMISLIB currently limits the resident code/data (not counting 
  74.       the "extra" allocation at installation time) to 64K.
  75.  
  76. ------------------------------------------------------------------------
  77.  
  78. After an INCLUDE AMIS.MAC, the following definitions and macros are available:
  79.  
  80. AMIS_VERSION
  81.     100 times the version of the specification to which the library
  82.     conforms (i.e. 123 = version 1.2.3).
  83.  
  84. AMISLIB_VERSION
  85.     100 times the version of this library
  86.  
  87. @Startup
  88.     Declare all segments and provide some startup code.
  89.     Usage:    @Startup major,minor,stack
  90.     Arguments:
  91.     major    [opt] the minimum major version of DOS required to run
  92.     minor    [opt] the major minor version of DOS required to run
  93.     stack    [opt] the number of bytes of stack to provide at startup
  94.     Note:
  95.     If either <major> or <minor> is blank, the program will not
  96.     check the DOS version at startup.  If <stack> is blank, a
  97.     default stack of 256 bytes will be provided in memory models
  98.     other than Tiny (there is no stack in Tiny model, so this value
  99.     will be ignored).
  100.  
  101. @Startup2
  102.     Provide additional startup code at the program's actual entry
  103.     point. 
  104.     Usage:    @Startup2 psp
  105.     Arguments:
  106.     psp    [opt] if non-blank, allocate a public variable named __psp
  107.     Note:
  108.     <psp> should be blank if some other module (such as the C
  109.     runtime library) provides a public variable named __psp.
  110.  
  111. RESIDENT_CODE
  112.     The name of the segment to ASSUME or use in overrides when accessing
  113.     data within the part of the program which will remain resident.
  114.  
  115. TGROUP
  116.     Group containing all resident segments in the TSR.    See also
  117.     TGROUP@ and TSRgroup@.
  118.  
  119. TGROUP@
  120.     Symbol to use when loading a segment register to access the TSRs
  121.     resident portion in the executable.     In Tiny model, this will load
  122.     the value of TGROUP from a memory location; in other memory models,
  123.     it is identical to TGROUP.
  124.  
  125. TSRcode@
  126. TSRcodeEnd@
  127.     Delimit the code which will remain resident; some of the other
  128.     macros listed below will not function correctly unless within a
  129.     section of code delimited with TSRcode@ and TSRcodeEnd@.
  130.  
  131. TSRdata@
  132. TSRdataEnd@
  133.     Delimit the initialized data which will remain resident.  Requires the
  134.     use of TSRgroup@ to function properly.
  135.  
  136. TSRbss@
  137. TSRbssEnd@
  138.     Delimit the uninitialized data which will be placed in the resident
  139.     portion (but omitted from the disk image of the executable if
  140.     possible).    Requires the use of TSRgroup@ to function properly.
  141.  
  142. TSRgroup@
  143.     Declare TGROUP and force the correct ordering of TSRcode@, TSRdata@,
  144.     and TSRbss@.
  145.  
  146. DISPLAY_STRING
  147.     Output a '$'-terminated string to standard output via DOS.
  148.     Usage:
  149.     DISPLAY_STRING string,dataseg
  150.     Arguments:
  151.     string    the label of the string to be displayed
  152.     dataseg [opt] the segment of the string
  153.     Example:
  154.     DISPLAY_STRING banner
  155.     ...
  156.     ...
  157.     banner db "FOOBAR (c) 1992 Harry Q Bovik",13,10,"$"
  158.  
  159. CHECK_DOS_VER
  160.     Ensure that the program is running under the proper version of DOS,
  161.     and terminate with an error message specifying the minimum required
  162.     version if not.
  163.     Usage:
  164.     CHECK_DOS_VER  major,minor
  165.     Example:
  166.     CHECK_DOS_VER 2,00
  167.  
  168. IF_INSTALLED
  169.     Conditionally branch somewhere if the TSR is already installed.
  170.     Usage:
  171.     IF_INSTALLED dest
  172.     Arguments:
  173.     dest     label to branch to if already installed
  174.     Return:
  175.     falls through with CF clear if not already installed
  176.     branches with CF set and AH = multiplex number if installed
  177.  
  178. IF_HOTKEY_USED
  179.     Conditionally branch somewhere if one or more of the TSR's hotkeys
  180.     are already in use.
  181.     Usage:
  182.     IF_HOTKEY_USED dest
  183.     Arguments:
  184.     dest     label to branch to if hotkey conflict
  185.     Return:
  186.     falls through with CF clear if no hotkey conflict
  187.     branches with CF set and AX = bitmask of conflict types
  188.                 bit 0: exact key already in use
  189.                 bit 1: superset key already in use
  190.                 bit 2: subset key already in use
  191.  
  192. INSTALL_TSR
  193.     Allocate memory for the resident code, copy the resident code to the
  194.     allocated memory, hook all interrupts used by the TSR, optionally
  195.     call an initialization function, and terminate back to DOS.
  196.     Usage:
  197.     INSTALL_TSR extra,fit,high,init,if_inst,on_err,more_flags
  198.     Arguments:
  199.     extra    [opt] number of additional paragraphs needed in resident part
  200.     fit    [opt] FIRST or BEST (default) -fit allocation
  201.     high    [opt] HIGHONLY to only use UMBs, LOWONLY to only use
  202.             conventional memory, TOPMEM to allocate block at high 
  203.             end of conventional memory if no UMBs, TOPLOW
  204.             to only use top end of conventional memory
  205.     init    [opt] function to call after installing TSR but before exiting
  206.     if_inst [opt] label to branch to if already installed
  207.     on_err    [opt] label to branch to if unable to install
  208.     more_flags [opt] label of byte containing additional flags to be ORed
  209.            with those automatically set by <fit> and <high>
  210.     Notes:
  211.     If 'init' is specified, the indicated function will be called with
  212.         AX = segment at which TSR was loaded
  213.     If 'if_inst' is spe